Skip to content

docs(site): drop the v3.5 pruning migration note - #23345

Draft
bloxster wants to merge 1 commit into
mainfrom
docs/drop-v35-pruning-migration-note
Draft

docs(site): drop the v3.5 pruning migration note#23345
bloxster wants to merge 1 commit into
mainfrom
docs/drop-v35-pruning-migration-note

Conversation

@bloxster

@bloxster bloxster commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator

Removes the Breaking change in v3.5 admonition from the Pruning Modes page, keeping the parts of it that are not version-specific.

Why

The note is addressed to a reader who no longer exists. It is a v3.4 → v3.5 upgrade notice sitting near the top of the current docs, which now describe v3.6. A "breaking change in v3.5" is simply not news to someone running 3.6 — the break is two versions behind them, and the page already carries an As of v3.6 tip directly above it. Anyone actually upgrading to v3.5 still gets the note in the versioned archive at /v3.5/, which is where version-specific migration guidance belongs.

Its steady state is also already documented permanently: the retention behaviour it announced is stated in the comparison table and in the Full Node / Blocks Node / Minimal Node sections — the EIP-8252 window, 262,144 blocks (~36.4 days), and what each mode prunes. What was left in the note was a v3.4-vs-v3.5 diff.

One incidental find while removing it: the note told operators to set --prune.distance.blocks=keep-post-merge, but that flag is a cli.Uint64Flag (node/cli/flags.go), so it accepts only a number and the suggested command cannot parse. The equivalent is the sentinel 18446744073709551615 (KeepPostMergeBlocksPruneMode = Distance(math.MaxUint64)), not worth putting in front of readers. release/3.5 was already corrected and drops that wording; main and release/3.6 still carry it.

What was kept

Two statements in the note were durable rather than version-specific, so they moved into the mode descriptions:

  • Pruning is irreversible — added to the paragraph about switching modes, since that is where the decision gets made.
  • A Full Node cannot serve history beyond its window, and the Blocks Node is the alternative — added to the Full Node rationale. The old text stated the mechanism ("older blocks... are pruned") but not the consequence or the way out.

Net: −24 lines, +6.

Verification

  • 78/78 python guards, generate-llms.py --check green (73 pages), tsc --noEmit clean, npm run build SUCCESS.
  • llms.txt / llms-full.txt regenerated (the page feeds them).
  • The build runs with onBrokenAnchors: 'throw', so the new #blocks-node link is verified to resolve.
  • Rendered page checked in a local production build: note gone, both new sentences present, anchor target present.

Notes for reviewers

main and release/3.6 share this page, so this needs a forward-port to release/3.6 to survive the docs cutover — happy to open that, or fold it into #23283 which already targets that branch.

Separately, and not touched here: the Minimal Node paragraph says it "does not retain state history", while the table says it keeps state within the last 100,000 blocks. The table matches the source (MinimalMode sets both Blocks and History to 100,000). Worth a follow-up.

…lies

The note documented the v3.4 → v3.5 change to --prune.mode=full. Its steady
state is already described in the table and the per-mode sections, so what
remained was a version diff plus one wrong instruction:
--prune.distance.blocks is a Uint64Flag, so the suggested
`--prune.distance.blocks=keep-post-merge` cannot parse.

Fold the two parts that are not version-specific into the mode descriptions —
that pruning cannot be undone without a re-sync, and that a Full Node cannot
serve history beyond its window, for which the Blocks Node is the answer.

Co-authored-by: Bloxster <gianni.morselli@erigon.tech>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants